package com.smart.community.feign.property.service;

import com.smart.community.feign.property.dto.PropertyCompanyPaymentInfoDTO;
import com.smart.community.feign.property.fallback.PropertyCompanyPaymentFeignFallbackFactory;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.cloud.openfeign.FeignClient;
import org.springframework.web.bind.annotation.*;

/**
 * 物业公司支付Feign接口
 * 
 * 提供物业公司支付相关的远程调用接口，包括收款码获取等功能
 * 业务流程：房户ID → 物业公司ID → 收款码信息
 * 
 * @author Wu.Liang
 * @version 1.0.0
 * @since 2025-01-30
 */
@Tag(name = "物业公司支付Feign接口", description = "物业公司支付相关Feign接口，支持收款码获取等功能")
@FeignClient(
    name = "smart-community-property",
    path = "/property/company-payment",
    fallbackFactory = PropertyCompanyPaymentFeignFallbackFactory.class,
    contextId = "propertyCompanyPaymentFeign"
)
public interface IPropertyCompanyPaymentFeign {
    
    /**
     * 根据物业公司ID获取收款码信息
     * 
     * 核心支付接口：通过物业公司ID获取收款二维码、支付账户等信息
     * 用于缴费系统展示收款码，支持扫码支付
     * 
     * @param propertyCompanyId 物业公司ID
     * @return 物业公司支付信息，包含收款码、支付账户等
     */
    @Operation(summary = "根据物业公司ID获取收款码信息", description = "缴费系统核心接口，获取物业公司收款码和支付信息")
    @GetMapping("/feign/property-company/{propertyCompanyId}/payment-info")
    PropertyCompanyPaymentInfoDTO getPropertyCompanyPaymentInfo(@Parameter(description = "物业公司ID") @PathVariable("propertyCompanyId") Long propertyCompanyId);
    
    /**
     * 根据房户ID获取收款码信息
     * 
     * 便捷接口：通过房户ID直接获取对应的物业公司收款码信息
     * 内部调用区域层级关系Feign接口获取物业公司ID，再获取收款码信息
     * 
     * @param householdId 房户ID
     * @return 物业公司支付信息，包含收款码、支付账户等
     */
    @Operation(summary = "根据房户ID获取收款码信息", description = "便捷接口，通过房户ID直接获取物业公司收款码信息")
    @GetMapping("/feign/household/{householdId}/payment-info")
    PropertyCompanyPaymentInfoDTO getPaymentInfoByHouseholdId(@Parameter(description = "房户ID") @PathVariable("householdId") Long householdId);
    
    /**
     * 批量根据物业公司ID获取收款码信息
     * 
     * 用于批量缴费、批量查询等场景，提高查询效率
     * 
     * @param propertyCompanyIds 物业公司ID列表
     * @return 物业公司ID与支付信息的映射关系
     */
    @Operation(summary = "批量根据物业公司ID获取收款码信息", description = "批量获取物业公司收款码信息，提高查询效率")
    @PostMapping("/feign/property-companies/payment-info")
    java.util.Map<Long, PropertyCompanyPaymentInfoDTO> getPropertyCompanyPaymentInfoBatch(@Parameter(description = "物业公司ID列表") @RequestBody java.util.List<Long> propertyCompanyIds);
}
